home *** CD-ROM | disk | FTP | other *** search
/ Creative Computers / Creative Computers CD-ROM, Volume 1 (Legendary Design Technologies, Inc.)(1994).iso / shareware / telecom / term_4.1 / documentation / xpr_libs / xprzmodem.doc < prev    next >
Text File  |  1994-11-17  |  35KB  |  683 lines
  1.  
  2.                     Documentation for XPRZModem.library
  3.               Version 2.10, 12 February 1991, by Rick Huebner
  4.  
  5. |---
  6. |           Update comments for XprZmodem.Library
  7. |    Version 2.50 Update, 15 November 1991, by William M. Perkins
  8. |    Version 2.51 bug fix, 29 January 1992, by John Tillema
  9. |    Version 2.52 recompiled, 6 March 1992, by William M. Perkins
  10. |    Version 2.54 Update, 28 June 1993, by Olaf `Olsen' Barthel
  11. |      Proto additions for the SAS 5.10B Compiler by Jim Cooper
  12. |---
  13.  
  14. |---
  15. |    All of my additions to this documentation are indicated by
  16. |  <--  this left margin braketing.   -WMP-
  17. |---
  18.  
  19. 1.  Introduction (or "What is this thing, anyway?")
  20. ---------------------------------------------------
  21.  
  22.      XPRZModem.library is an Amiga shared library (with full Lattice C
  23. source code) which provides ZModem file transfer capability to any
  24. XPR-compatible communications program.  The XPR external protocol standard
  25. describes an interface method which allows various file transfer protocols
  26. to be implemented as Amiga shared libraries which may then be used
  27. interchangeably in any compatible communications program.  This takes a
  28. heavy load off of the comm program author, who no longer has to support
  29. scads of different file transfer protocols (many of which are quite tricky
  30. to code) in their program in order to make it widely useful and popular.
  31. The comm program is also smaller and more efficient as a result, since all
  32. those obscure protocols (you know, the ones *you* don't need) are no longer
  33. taking up space.  The XPR standard also helps users, who can mix and match
  34. their favorite file transfer protocols (and implementations thereof) with
  35. their favorite comm programs.  And when new protocols are invented, the
  36. user simply plugs in a new library, and voila!, it's ready to use.
  37. Hopefully, making protocols easy to support will allow more and better comm
  38. programs to be written, as authors can concentrate on their programs
  39. instead of constantly re-inventing the wheel.
  40.  
  41.      Of course, for all of this wonderful stuff to happen, there needs to
  42. be a good selection of these XPR protocol libraries available to the
  43. public.  It's the classic chicken-and-egg problem; comm program authors
  44. won't be motivated to support the XPR standard unless there are a goodly
  45. number of protocols available for it.  And other programmers won't be
  46. motivated to write XPR protocol libraries until there are a goodly number
  47. of comm programs which can use them.  In an effort to do my bit [ B^) ] for
  48. the Amiga community, which has given me so many neat toys to play with over
  49. the past few years, I decided to try and help get the ball rolling.
  50.  
  51.      Hopefully, the early availability of a ZModem library will help
  52. stimulate interest in the XPR standard, resulting in better Amiga telecomms
  53. for all of us.  And by making my source code PD, I hope to help others
  54. interested in writing XPR protocol libraries by giving them some serious
  55. example code.  Also, having ZModem library code readily available to John
  56. Q. Hacker should help ensure a steady stream of new lemon-fresh enhanced
  57. ZModem libraries (with enzymes) for all of us to use in the future.
  58.  
  59.      Of course, no discussion of the XPR standard would be complete without
  60. giving proper credit to the author, Willy Langeveld of the Stanford Linear
  61. Accelerator Center.  Many thanks are due him for this effort.  If you have
  62. any further questions about the XPR standard, be sure and download the spec;
  63. it should be available on BIX (since he's a sysop there), or on most other
  64. major systems.  And I'll try to keep the current version available on my
  65. BBS, as well.
  66.  
  67.      All files in this archive which are not copyrighted are hereby
  68. released to the public domain (which they were anyway, by way of not being
  69. copyrighted, but I want to make sure YOU realize that).  Do as you like
  70. with them.  Please make lots of copies and distribute them all over the
  71. place, and make lots of derivative works, and everything!  Heck, you can
  72. even publicly perform and/or display this code if you can figure out how...
  73.  
  74.  
  75.  
  76. 2.  Installation (OK, enough chatter; let's get to work)
  77. --------------------------------------------------------
  78.  
  79.      Couldn't be easier.  Just copy the xprzmodem.library file into your
  80. LIBS: directory.  All XPR-compatible comm programs should provide a way for
  81. you to select which XPR protocol you wish to use, either by giving you a
  82. file requester showing LIBS:xpr*.library, or by automatically detecting
  83. these libraries and adding them into their menus.
  84.  
  85. WARNING:  Versions of VLT prior to revision 4.107 had a bug in the
  86. xpr_sflush() routine which caused random Guru 3 crashes on some systems.  If
  87. you're using a version of VLT older than 4.107, it would be a good idea to
  88. upgrade to the latest rev.  Besides, there's a bunch of new features you're
  89. missing, anyway...
  90.  
  91. ANOTHER WARNING:  Versions of VLT prior to 5.034 had a bug in the
  92. xpr_sread() function which caused them to (at least sometimes) fail to
  93. return any bytes received so far when an xpr_sread() call timed out.  This
  94. version of XPRZModem.library requires VLT version 5.034 or later.  (Yes,
  95. Willy, it really was broken B-))
  96.  
  97. |---
  98. |    XprZmodem.Library version 2.50 and 2.52 tested with WTerm version
  99. |    0.82 and Willy's term program, VLT version 5.045.  No problems
  100. |    occurred.  It should work fine with any term program that was able
  101. |    to work with the version 2.10 of XprZmodem.Library.    -WMP-
  102. |---
  103.  
  104. |---
  105. |    xprzmodem.library v2.54 *requires* Kickstart 2.04 or higher to
  106. |    work properly! Trying to use this library with any previous
  107. |    operating system revision will most certainly fail!
  108. |    All library texts are now localized, i.e. if a translation
  109. |    table for you preferred system language is available, the
  110. |    library will issue error messages and such in it. As of this
  111. |    writing only a German translation is available. I have included
  112. |    a blank catalog translation file (zmodem_blank.ct) for your
  113. |    convenience; feel free to translate it to your preferred
  114. |    language and mail it to me (see the address at the end of this
  115. |    document). It will be included in the next release.
  116. |---
  117.  
  118. 3.  Options
  119. -----------
  120.  
  121.      The XPR standard lays out two ways for the comm program user to
  122. specify options for the XPR protocol.  The more primitive option is for the
  123. comm program to provide a method of passing an option string to the XPR
  124. library before transferring files.  The precise format and usage of this
  125. option string is left up to the XPR protocol author; the comm program just
  126. sends it verbatim.  If an environment variable is found with the same name
  127. as the XPR protocol (i.e. there's a file in the ENV: directory called
  128. "xprzmodem"), the comm program is supposed to use this string (contents of
  129. file) to initialize the protocol options.  Also, a menu option or some such
  130. should normally be provided which will allow the user to be prompted for
  131. the option string interactively.
  132.  
  133.      Version 2.0 of the XPR standard created a new, more sophisticated way
  134. for the comm program user to specify XPR options.  If the comm program
  135. supports it, the XPR library can give the comm program a list of option
  136. prompts, and the comm program can then let the user interactively set the
  137. various options individually, possibly even using nice gadgets and stuff.
  138.  
  139.      In any case, no matter how your particular comm program feels like
  140. handling it, these are the options supported by this implementation of
  141. ZModem:
  142.  
  143.           T{Y|N|?|C}   Text translation mode:
  144.              TY = Text Yes; if receiving, translate CR/LF pairs or solo
  145.                   CR chars to normal Amiga LF chars.  Ignore data past ^Z.
  146.                   If sending, suggests to receiver that they should receive
  147.                   this file in text mode.
  148.              TN = Text No; receive file verbatim, without changes.  If
  149.                   sending, suggest to receiver that they receive this
  150.                   file verbatim, without translations.
  151.              T? = Text status unknown; if receiving, use sender's
  152.                   suggestion as to whether to do EOL translations or not.
  153.                   If sending, tell receiver to use default mode, 'cause we
  154.                   don't know either.
  155.              TC = Text mode